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Copyright notice . On receipt of this computer program and associated documentation (the 
software), the author grants you a nonexclusive license to execute the enclosed software. This 
software is copyrighted, You are prohibited from reproducing, translating, or distributing 
this software in any unauthorized manner, 



Distributed By 

The ATARI Program Exchange 
P.O. Box 3705 
Santa Clara. CA 95055 

To request an APX Product Catalog, write to the address above, or call toll-free: 

800/538-1862 (outside California) 

800/672-1850 (within California) 

Or call our Sales number, 408/727-5603 


Trademarks of Atari 

The following are trademarks of Atari, Inc. 
ATARI® 

ATARI 400” Home Computer 
ATARI 800” Home Computer 
ATARI 410” Program Recorder 
ATARI 810” Disk Drive 
ATARI 820” 40-Column Printer 
ATARI 822” Thermal Printer 
ATARI 825” 80-Column Printer 
ATARI 830” Acoustic Modem 
ATARI 850” Interface Module 


Printed in U.S.A. 




This APX diskette is unnotched to protect the software against 
accidental erasure. However, this protection also prevents a program 
from storing information on the diskette. The program you've 
purchased involves storing information. Therefore, before you can use 
the program, you must duplicate the contents of the diskette onto a 
notched diskette that doesn't have a write-protect tab covering the 
notch. 

To duplicate the diskette, call the Disk Operating System (DOS) menu 
and select option <T, Duplicate Disk. You can use this option with a 
single disk drive by manually swapping source (the APX diskette) and 
destination (a notched diskette) until the duplication process is 
complete. You can also use this option with multiple disk drive 
systems by inserting source and destination diskettes in two separate 
drives and letting the duplication process proceed automatically. 
(Note. This option copies sector by sector. Therefore, when the 
duplication is complete, any files previously stored on the 
destination diskette will have been destroyed.) 



Microsoft BASIC 


Cross— Reference TJtili-ty 


1 — Introduction 

Overview - The ATARI Microsoft BASIC Cross-Reference Utility (MXREF) is a 
program development tool. XREF produces directories of variable usage and line 
number references within ATARI Microsoft BASIC programs} it will not correctly 
process programs written in other BASIC dialects. 

MXREF can help you write programs in ATARI Microsoft BASIC by pointing out each 
reference to each variable and line number. The location of these references is 
frequently difficult to determine in large programs under development for longer 
than the author can remember every change. MXREF reports help answer the 
following common questions? 


1. Have I used this variable name somewhere else? 

2. Does another statement branch to this one? 

3. How did my program arrive at that statement? 

4. What caused the value of that variable to change? 

5. If I change this subroutine, what other code is affected? 


REQUIRED ACCESSORIES 

ATARI Microsoft BASIC (CX3126) 
40KB RAM 

ATARI 310 Disk Drive 


Soedai Terms - The term "LIST formatted program" refers to a program which has 
been saved to disk by the LIST command instead of by the SAVE command, By using 
the LIST command, ATARI Microsoft BASIC produces a file of the program in a 
format that can be printed or easily read by a BASIC program. To prepare a program 
for analysis by MXREF, transfer it to disk using the LIST command. 


2 — Gettin g Started 

1. Remove any program cartridge from the cartridge slot of your computer. 

2. If you want printed reports, turn on your printer. If you are using an ATARI 325 
30-column Printer, turn on your ATARI 350 Interface Module. 
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3. Turn on your disk drive. 

4. When the busy light goes out, open the disk drive door and insert the ATARI 
Microsoft BASIC Diskette with the label in the lower right-hand corner. 

5. Turn on your computer and TV set. 

6. ATARI Microsoft BASIC will load into your computer automatically. 

7. When the prompt displays, open the disk drive door, remove the ATARI Microsoft 
BASIC disk. 


Mote MXREF requires that you store your file on diskette in LIST format 
rather than in SAVE format. If you have stored it with a SAVE command, 
convert it at this time as follows (ABC is the example file name): 

i, Load your file into computer memory using the command 

LOAD "DJAEC" 

ii. Then copy it back to the disk using the command 

LIST “d:labc m 


3 — Running MXREF 

Insert the MXREF disk into the DISK DRIVE. Type the command RUN "DJMXREF" to 
load MXREF into computer memory and begin its execution. 

After a title screen displays, the following message appears: 

ENTER NAME OF 

LIST FILE TO 

BE indexed: 


Enter the name of the file containing the program to be analyzed which was saved in 
LIST format. With the above example, you would enter DJLABC. 

The following message then displays on the lower half of the screen? 

ENTER NAME OF 

REPORT OUTPUT 

file: 


At this point enter the name of the device or file you want' the report to be copied 
to. A common response would be PJ for directing the report to the printer. Do not 
enter S3 since the report will display on the screen in any event. You can't proceed 
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until you specify an output destination. If you want only the screen output, direct 
the output to a disk file which you can later delete, e.g., DJJUNK. 

The system will now stir a bit and attempt to locate the specified LIST-formatted 
file. If it can't locate your input file, the following message displays asking you to 
insert the disk containing the input file in your disk drive} 

PLEASE INSTALL 

d:labc 

THEN PRESS RETURN 


After MXREF locates the file, the following message displays indicating the line 
number of your program that MXREF is now analyzing} 


NOW SCANNING 
STATEMENT 
NUMBER 130 


After MXREF analyzes the last statement in your program, the report displays on 
the screen as it is transmitted to the output file or device you designated. 


4 — Report 

MXREF produces a report with three sections} the title section, the variable 
reference section, and the line number reference section. A sample printed report is 
at the end of this manual. 

Report Title - The first two lines of the report identify the file analyzed to produce 
the report and the value of TIME* when the report was generated. The TIME* value 
is useful when you make several reports on the same program during a single 
sitting. The title section for our example might look like this? 

Cross-Reference of DJLABC 

03J30511 


Variable References - This section lists the variables located by MXREF. They are 
listed in alphabetical order on the left hand side of the page/screen. To the right 
of each variable name are, in line number order, all the line numbers of statements 
referencing the variable. If the variable is referenced more than once within a 
statement, the statement's line number appears on the right-hand side as many 
times as the variable is referenced within. 

Line Number Reference - This section lists all of the line numbers referenced within 
a statement in the program along the left-hand side of the report. Three periods 
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follow each line number to highlight it. If a line number does not appear within the 
program as the object of a transfer statement (e.g., GQSUB) or a RESTORE 
statement, it will not appear in the report on the left-hand side. To the right of 
each entry are all the line numbers containing references to the indicated line 
number. There is one entry for each reference to the line number and they are in 
line number order. 


5 — Error Messages 

The error messages produced by MXREF and the action normally required to correct 
the associated problem are as follows! 

PRINTER NOT OPERABLE - This message is produced when an attempt to 
access the report output device results in an error 139J this is most commonly 
caused by the printer being turned off. After a delay, the program will 
reattempt to access the output device in the hope that it will have been made 
available, i.e„ turned on and in ONLINE mode. 

DJABC NOT SAVED IN LIST FORMAT - The input file was not in the format 
required by MXREF. MXREF will terminate since it will be neccessary to 
convert the file to LIST format as described in section 2. This is the 
interpretation of an error 137 by MXREF. 

PLEASE INSTALL D5LABC THEN PRESS RETURN - The error 170 is interpreted 
as the file to be analyzed not yet being positioned on the disk drive. MXREF 
will wait until you press a key and then it will look for the file again. 

ABNORMAL TERMINATION - An error number was encountered other than 
those mentioned above. The error number can be displayed by entering ?ERR. 
The program will have terminated. MXREF will have to be reloaded to proceed. 


— Technical Discussion 

The following notes describe the internal structure of MXREF and do not need to be 
read to use the system fully. They are only for the curious. 

MXREF consists of two files* MXREF and X2. MXREF performs some initialization 
and obtains the input and output parameters. This information is then passed to X2 
for performance of the analysis and production of the report. MXREF has been 
broken into two parts to reduce the amount of memory required for its execution. A 
third program file for report generation would have been broken out except for the 
concomitant handling problems. 

MXREF contains in DATA statements all of the key words recognized by BASIC, 
These words are read into string arrays from the DATA statements. The string 
arrays are passed on to X2 via Microsoft BASIC COMMON statement so that the 
space occupied by the DATA statements can be recovered. We also end up 
recovering all of the space associated with the title screen and parameter collection. 

X2 is delicate. Emphasis has been placed on always producing a correct and 
complete report at the expense of speed, The following steps are followed to 
collect the relevant data from each statement! 

1. A program line is read into WORK$. 
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2. Quoted strings are masked out of the statement. 

3. Remarks are masked out. 

4. DATA, DEFSNG, DEFDBL and DEFSTR statements are masked out. 

5. Operators and delimiters are removed. At this point all that should remain 
are variables, line numbers, numeric constants and keywords. 

6. On the basis of what keywords are encountered, MXREF determines the 
difference between a numeric constant and a line number. A key word is 
separated from a variable name by its appearance in the keyword strings. 
Which of the keyword strings it appears in indicates its significance for 
locating line numbers. 

7. As references to line numbers and variables are encountered, two integers 
are placed in the REF array. The second is the line number of the statement 
containing the reference and the first, if positive, is the line number 
referenced. If the first is negative, then it is an index into the list of known 
variable names, VAR$. 


That this program can be written entirely in ATARI Microsoft BASIC is an 
indication of the power of the language for developers. I invite the 
contribution to APX of a faster FORTH or assembly language version of MXREF 
if credit is given for the algorithm. 
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/-• — Sample F2.ep ort 
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Cross Reference of DJTEEST 
0 0 J 1 4 1 1 2 


Variable References 


A* 

480 

49 0 

530 

540 


580 

590 

630 

640 


650 

720 

720 

730 


740 

750 

760 

830 


830 

840 

850 

860 


870 




D 

350 

380 

390 

400 

F02 

130 

210 

220 

240 


240 




FI 

130 

150 

160 

170 


180 

190 

200 

230 


230 




FNAME$ 

20 

710 

730 

730 


730 

730 

760 

760 


770 




I 

140 

470 

520 

570 


620 

650 



KW* 

30 

650 



LNAMEf 

20 

820 

840 

840 


840 

840 

870 

870 


880 

900 



NREF 

30 

450 



NTE 

380 

390 

400 


NVAR 

30 

450 



RW* 

20 

460 

490 

490 


510 

540 

540 

560 


590 

590 

610 

640 


640 




V 

120 

150 

160 

170 


180 

190 

200 

210 


220 




Z1 

370 

380 

410 

410 

Z2 

370 

390 

420 

420 

Z3 

370 

400 

430 

430 


440 




ZCR 

360 

410 

420 

430 


Line Number References 
440 


380 ♦♦ ♦ 



720 ♦ ♦ ♦ 

720 

780 

77 0 ♦ « ♦ 

730 

740 

790 . . . 

750 


S20 * * t 

900 


330 + ♦ ♦ 

830 

890 

880 . . ♦ 

840 

850 

900 . ♦ . 

860 




* 




Limited Warranty on Media and Hardware Accessories. Atari, Inc. (“Atari”) warrants to the original 
consumer purchaser that the media on which APX Computer Programs are recorded and any 
hardware accessories sold by APX shall be free from defects in material or workmanship for a 
period of thirty (30) days from the date of purchase. If you discover such a defect within the 30-day 
period, call APX for a return authorization number, and then return the product to APX along with 
proof of purchase date. We will repair or replace the product at our option. If you ship an APX 
product for in-warranty service, we suggest you package it securely with the problem indicated in 
writing and insure it for value, as Atari assumes no liability for loss or damage incurred during 
shipment. 

This warranty shall not apply if the APX product has been damaged by accident, unreasonable 
use, use with any non-ATARI products, unauthorized service, or by other causes unrelated to 
defective materials or workmanship. 

Any applicable implied warranties, including warranties of merchantability and fitness for a 
particular purpose, are also limited to thirty (30) days from the date of purchase. Consequential or 
incidental damages resulting from a breach of any applicable express or implied warranties are 
hereby excluded. 

The provisions of the foregoing warranty are valid in the U.S. only. This warranty gives you 
specific legal rights and you may also have other rights which vary from state to state. Some states 
do not allow limitations on how long an implied warranty lasts, and/or do not allow the exclusion of 
incidental or consequential damages, so the above limitations and exclusions may not apply to 
you. 

Disclaimer of Warranty on APX Computer Programs. Most APX Computer Programs have been 
written by people not employed by Atari. The programs we select for APX offer something of value 
that we want to make available to ATARI Home Computer owners. In order to economically offer 
these programs to the widest number of people, APX Computer Programs are not rigorously 
tested by Atari and are sold on an “as is” basis without warranty of any kind. Any statements 
concerning the capabilities or utility of APX Computer Programs are not to be construed as 
express or implied warranties. 

Atari shall have no liability or responsibility to the original consumer purchaser or any other 
person or entity with respect to any claim, loss, liability, or damage caused or alleged to be caused 
directly or indirectly by APX Computer Programs. This disclaimer includes, but is not limited to, 
any interruption of services, loss of business or anticipatory profits, and/or incidental or 
consequential damages resulting from the purchase, use, or operation of APX Computer 
Programs. 

Some states do not allow the limitation or exclusion of implied warranties or of incidental or 
consequential damages, so the above limitations or exclusions concerning APX Computer 
Programs may not apply to you. 


For the complete list of current 
APX programs, ask your ATARI retailer 
for the APX Product Catalog 




ATARI' 
PROGRAM 
EXCHANGE 

P.O. Box 3705 
Santo Clara. CA 95055 



We re interested in your experiences with A PX programs 
and documentation, both favorable and unfavorable. 
Many of our authors are eager to improve their programs 
if they know what you want. And, of course, we want to 
know about any bugs that slipped by us. so that the 
author can fix them. We also want to know whether our 

1. Name and APX number of program. 


Review Form 


instructions are meeting your needs. You are our best 
source for suggesting improvements! Please help us by 
taking a moment to fill in this review sheet. Fold the sheet 
in thirds and seal it so that the address on the bottom of 
the back becomes the envelope front. Thank you for 
helping us! 


2. If you have problems using the program, please describe them here. 


3. What do you especially like about this program? 


4. What do you think the program s weaknesses are? 


5. How can the catalog description be more accurate or comprehensive? 


6. On a scale of i to 10. i being "poor" and 10 being "excellent”, please rate the following aspects of this program: 
Easy to use 

User-oriented (e.g.. menus, prompts, clear language) 

Enjoyable 

Self-instructive 

Useful (non-game programs) 

Imaginative graphics and sound 







7. Describe any technical errors you found in the user instructions (please give page numbers). 


8. What did you especially like about the user instructions? 


9. What revisions or additions would improve these instructions? 


10. On a scale of 1 to 10, 1 representing “poor” and 10 representing “excellent”, how would you rate the user 
instructions and why? 


11. Other comments about the program or user instructions: 


rfom 


STAMP 


ATARI Program Exchange 

P.O. Box 3705 

Santa Clara. CA 95055 


[seal herej 








